.. _envoy_api_file_api/filter/accesslog.proto: api/filter/accesslog.proto ========================== .. _envoy_api_msg_filter.AccessLogEntry: filter.AccessLogEntry --------------------- `[filter.AccessLogEntry proto] `_ .. code-block:: json { "request_method": "...", "start_time": "{...}", "protocol_variant": "...", "response_flags": [], "upstream_host": "...", "upstream_cluster": "...", "destination_host": "...", "request_body_bytes": "{...}", "response_body_bytes": "{...}", "request_headers_bytes": "{...}", "response_headers_bytes": "{...}", "secure": "{...}", "health_check": "{...}", "response_code": "{...}", "user_agent": "...", "path": "...", "referer": "...", "forwarded_for": "...", "request_id": "...", "authority": "...", "response_duration": "{...}", "upstream_service_duration": "{...}", "original_path": "...", "metadata": "{...}", "request_headers": [], "response_headers": [], "tls_sni_hostname": "...", "tls_version": "...", "tls_cipher_suite": "{...}" } .. _envoy_api_field_filter.AccessLogEntry.request_method: request_method (:ref:`RequestMethod `) The HTTP request method (RFC 7231/2616) .. _envoy_api_field_filter.AccessLogEntry.start_time: start_time (`Timestamp `_) The time that Envoy started servicing this request .. _envoy_api_field_filter.AccessLogEntry.protocol_variant: protocol_variant (:ref:`filter.AccessLogEntry.Protocol `) .. _envoy_api_field_filter.AccessLogEntry.response_flags: response_flags (:ref:`filter.AccessLogEntry.ResponseFlag `) Status flags about the response. .. _envoy_api_field_filter.AccessLogEntry.upstream_host: upstream_host (`string `_) The upstream host URL (Envoy connects to). For example, tcp://ip:port for TCP connections. IPv6 addresses should be stored in canonical (compressed) format using [address]:port notation. .. _envoy_api_field_filter.AccessLogEntry.upstream_cluster: upstream_cluster (`string `_) The Upstream Cluster that the upstream host belongs to. .. _envoy_api_field_filter.AccessLogEntry.destination_host: destination_host (`string `_) This field is the IP and port on which the request from the user was received, stored in ipv4:port or [ipv6]:port format. .. _envoy_api_field_filter.AccessLogEntry.request_body_bytes: request_body_bytes (`UInt64Value `_) Size of the HTTP request body in bytes .. _envoy_api_field_filter.AccessLogEntry.response_body_bytes: response_body_bytes (`UInt64Value `_) Size of the HTTP response body in bytes .. _envoy_api_field_filter.AccessLogEntry.request_headers_bytes: request_headers_bytes (`UInt64Value `_) Size of the HTTP request headers in bytes .. _envoy_api_field_filter.AccessLogEntry.response_headers_bytes: response_headers_bytes (`UInt64Value `_) Size of the HTTP response headers in bytes .. _envoy_api_field_filter.AccessLogEntry.secure: secure (`BoolValue `_) Whether the request arrived via a secure (TLS) protocol .. _envoy_api_field_filter.AccessLogEntry.health_check: health_check (`BoolValue `_) Whether the request is a HealthCheck request .. _envoy_api_field_filter.AccessLogEntry.response_code: response_code (`UInt32Value `_) The HTTP response code .. _envoy_api_field_filter.AccessLogEntry.user_agent: user_agent (`string `_) User agent as sent by client HTTP .. _envoy_api_field_filter.AccessLogEntry.path: path (`string `_) Path This is the Path portion from the incoming request URI .. _envoy_api_field_filter.AccessLogEntry.referer: referer (`string `_) Referer header as sent by client HTTP (Referer is spelled to match the HTTP spec, not English). .. _envoy_api_field_filter.AccessLogEntry.forwarded_for: forwarded_for (`string `_) X-Forwarded-For request header .. _envoy_api_field_filter.AccessLogEntry.request_id: request_id (`string `_) X-Request-Id request header This header is used by Envoy to uniquely identify a request. It will be generated for all external requests and internal requests that do not already have a request ID. So this field can be guaranteed to exist and be unique for request tracing purposes. .. _envoy_api_field_filter.AccessLogEntry.authority: authority (`string `_) HTTP2 :authority header value or HTTP1.1 Host header value .. _envoy_api_field_filter.AccessLogEntry.response_duration: response_duration (`Duration `_) Duration (milliseconds) The total duration it took to service this request from the StartTime until the response was written to the user. .. _envoy_api_field_filter.AccessLogEntry.upstream_service_duration: upstream_service_duration (`Duration `_) Upstream Service Time Duration From the X-Envoy-Upstream-Service-Time response header. This is the amount it took the upstream server to service the request. .. _envoy_api_field_filter.AccessLogEntry.original_path: original_path (`string `_) Original Path from the X-Envoy-Original-Path header. .. _envoy_api_field_filter.AccessLogEntry.metadata: metadata (`Struct `_) All metadata encountered during request processing, including endpoint selection. This can be used to associate IDs attached to the various configurations used to process this request with the access log entry. For example, a route created from a higher level forwarding rule with some ID can place that ID in this field and cross reference later. It can also be used to determine if a canary endpoint was used or not. .. _envoy_api_field_filter.AccessLogEntry.request_headers: request_headers (:ref:`HeaderValue `) Headers configured for logging but not covered by a specific field. .. _envoy_api_field_filter.AccessLogEntry.response_headers: response_headers (:ref:`HeaderValue `) .. _envoy_api_field_filter.AccessLogEntry.tls_sni_hostname: tls_sni_hostname (`string `_) SNI hostname from handshake. .. _envoy_api_field_filter.AccessLogEntry.tls_version: tls_version (:ref:`filter.AccessLogEntry.TLSVersion `) .. _envoy_api_field_filter.AccessLogEntry.tls_cipher_suite: tls_cipher_suite (`UInt32Value `_) TLS Cipher suite negotiated during TLS handshake. The value is four hex digits defined by the IANA TLS Cipher Suite Registry, eg, "009C" for TLS_RSA_WITH_AES_128_GCM_SHA256. Here is is expressed as an integer. .. _envoy_api_enum_filter.AccessLogEntry.Protocol: Enum filter.AccessLogEntry.Protocol ----------------------------------- `[filter.AccessLogEntry.Protocol proto] `_ Incoming protocol variation spoken .. _envoy_api_enum_value_filter.AccessLogEntry.Protocol.PROTOCOL_UNSPECIFIED: PROTOCOL_UNSPECIFIED *(DEFAULT)* ⁣ .. _envoy_api_enum_value_filter.AccessLogEntry.Protocol.HTTP10: HTTP10 ⁣ .. _envoy_api_enum_value_filter.AccessLogEntry.Protocol.HTTP11: HTTP11 ⁣ .. _envoy_api_enum_value_filter.AccessLogEntry.Protocol.HTTP2: HTTP2 ⁣ .. _envoy_api_enum_filter.AccessLogEntry.ResponseFlag: Enum filter.AccessLogEntry.ResponseFlag --------------------------------------- `[filter.AccessLogEntry.ResponseFlag proto] `_ This enum defines the various things that may have occurred while processing a request. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.FAILED_LOCAL_HEALTHCHECK: FAILED_LOCAL_HEALTHCHECK *(DEFAULT)* ⁣Local server healthcheck failed. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.NO_HEALTHY_UPSTREAM: NO_HEALTHY_UPSTREAM ⁣No healthy upstream. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.UPSTREAM_REQUEST_TIMEOUT: UPSTREAM_REQUEST_TIMEOUT ⁣Request timeout on upstream. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.LOCAL_RESET: LOCAL_RESET ⁣Local codec level reset was sent on the stream. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.UPSTREAM_REMOTE_RESET: UPSTREAM_REMOTE_RESET ⁣Remote codec level reset was received on the stream. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.UPSTREAM_CONNECTION_FAILURE: UPSTREAM_CONNECTION_FAILURE ⁣Local reset by a connection pool due to an initial connection failure. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.UPSTREAM_CONNECTION_TERMINATION: UPSTREAM_CONNECTION_TERMINATION ⁣If the stream was locally reset due to connection termination. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.UPSTREAM_OVERFLOW: UPSTREAM_OVERFLOW ⁣The stream was reset because of a resource overflow. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.NO_ROUTE_FOUND: NO_ROUTE_FOUND ⁣No route found for a given request. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.DELAY_INJECTED: DELAY_INJECTED ⁣Request was delayed before proxying. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.FAULT_INJECTED: FAULT_INJECTED ⁣Abort with error code was injected. .. _envoy_api_enum_value_filter.AccessLogEntry.ResponseFlag.RATE_LIMITED: RATE_LIMITED ⁣Request was ratelimited locally by rate limit filter. .. _envoy_api_enum_filter.AccessLogEntry.TLSVersion: Enum filter.AccessLogEntry.TLSVersion ------------------------------------- `[filter.AccessLogEntry.TLSVersion proto] `_ TLS Version or VERSION_UNSPECIFIED if TLS was not used .. _envoy_api_enum_value_filter.AccessLogEntry.TLSVersion.VERSION_UNSPECIFIED: VERSION_UNSPECIFIED *(DEFAULT)* ⁣ .. _envoy_api_enum_value_filter.AccessLogEntry.TLSVersion.TLSv1: TLSv1 ⁣ .. _envoy_api_enum_value_filter.AccessLogEntry.TLSVersion.TLSv1_1: TLSv1_1 ⁣ .. _envoy_api_enum_value_filter.AccessLogEntry.TLSVersion.TLSv1_2: TLSv1_2 ⁣ .. _envoy_api_enum_value_filter.AccessLogEntry.TLSVersion.TLSv1_3: TLSv1_3 ⁣ .. _envoy_api_msg_filter.ComparisonFilter: filter.ComparisonFilter ----------------------- `[filter.ComparisonFilter proto] `_ Filter on some integer comparison. .. code-block:: json { "op": "...", "value": "{...}" } .. _envoy_api_field_filter.ComparisonFilter.op: op (:ref:`filter.ComparisonFilter.Op `) .. _envoy_api_field_filter.ComparisonFilter.value: value (:ref:`RuntimeUInt32 `) Value to compare against. .. _envoy_api_enum_filter.ComparisonFilter.Op: Enum filter.ComparisonFilter.Op ------------------------------- `[filter.ComparisonFilter.Op proto] `_ Comparison operator. .. _envoy_api_enum_value_filter.ComparisonFilter.Op.EQ: EQ *(DEFAULT)* ⁣ .. _envoy_api_enum_value_filter.ComparisonFilter.Op.GE: GE ⁣ .. _envoy_api_msg_filter.StatusCodeFilter: filter.StatusCodeFilter ----------------------- `[filter.StatusCodeFilter proto] `_ Filters on HTTP response/status code. .. code-block:: json { "comparison": "{...}" } .. _envoy_api_field_filter.StatusCodeFilter.comparison: comparison (:ref:`filter.ComparisonFilter `) .. _envoy_api_msg_filter.DurationFilter: filter.DurationFilter --------------------- `[filter.DurationFilter proto] `_ Filters on total request duration in milliseconds. .. code-block:: json { "comparison": "{...}" } .. _envoy_api_field_filter.DurationFilter.comparison: comparison (:ref:`filter.ComparisonFilter `) .. _envoy_api_msg_filter.NotHealthCheckFilter: filter.NotHealthCheckFilter --------------------------- `[filter.NotHealthCheckFilter proto] `_ Filters for requests that are not health check requests. A health check request is marked by the health check filter. .. code-block:: json { } .. _envoy_api_msg_filter.TraceableFilter: filter.TraceableFilter ---------------------- `[filter.TraceableFilter proto] `_ Filters for requests that are traceable. See the tracing overview for more information on how a request becomes traceable. .. code-block:: json { } .. _envoy_api_msg_filter.RuntimeFilter: filter.RuntimeFilter -------------------- `[filter.RuntimeFilter proto] `_ Filters for random sampling of requests. Sampling pivots on the header x-request-id being present. If x-request-id is present, the filter will consistently sample across multiple hosts based on the runtime key value and the value extracted from x-request-id. If it is missing, the filter will randomly sample based on the runtime key value. .. code-block:: json { "runtime_key": "..." } .. _envoy_api_field_filter.RuntimeFilter.runtime_key: runtime_key (`string `_) Runtime key to get the percentage of requests to be sampled. This runtime control is specified in the range 0-100 and defaults to 0. .. _envoy_api_msg_filter.AndFilter: filter.AndFilter ---------------- `[filter.AndFilter proto] `_ Performs a logical “and” operation on the result of each filter in filters. Filters are evaluated sequentially and if one of them returns false, the filter returns false immediately. .. code-block:: json { "filters": [] } .. _envoy_api_field_filter.AndFilter.filters: filters (:ref:`filter.AccessLogFilter `) .. _envoy_api_msg_filter.OrFilter: filter.OrFilter --------------- `[filter.OrFilter proto] `_ Performs a logical “or” operation on the result of each individual filter. Filters are evaluated sequentially and if one of them returns true, the filter returns true immediately. .. code-block:: json { "filters": [] } .. _envoy_api_field_filter.OrFilter.filters: filters (:ref:`filter.AccessLogFilter `) .. _envoy_api_msg_filter.AccessLogFilter: filter.AccessLogFilter ---------------------- `[filter.AccessLogFilter proto] `_ .. code-block:: json { "status_code_filter": "{...}", "duration_filter": "{...}", "not_health_check_filter": "{...}", "traceable_filter": "{...}", "runtime_filter": "{...}", "and_filter": "{...}", "or_filter": "{...}" } .. _envoy_api_field_filter.AccessLogFilter.status_code_filter: status_code_filter (:ref:`filter.StatusCodeFilter `) Only one of :ref:`status_code_filter `, :ref:`duration_filter `, :ref:`not_health_check_filter `, :ref:`traceable_filter `, :ref:`runtime_filter `, :ref:`and_filter `, :ref:`or_filter ` may be set. .. _envoy_api_field_filter.AccessLogFilter.duration_filter: duration_filter (:ref:`filter.DurationFilter `) Only one of :ref:`status_code_filter `, :ref:`duration_filter `, :ref:`not_health_check_filter `, :ref:`traceable_filter `, :ref:`runtime_filter `, :ref:`and_filter `, :ref:`or_filter ` may be set. .. _envoy_api_field_filter.AccessLogFilter.not_health_check_filter: not_health_check_filter (:ref:`filter.NotHealthCheckFilter `) Only one of :ref:`status_code_filter `, :ref:`duration_filter `, :ref:`not_health_check_filter `, :ref:`traceable_filter `, :ref:`runtime_filter `, :ref:`and_filter `, :ref:`or_filter ` may be set. .. _envoy_api_field_filter.AccessLogFilter.traceable_filter: traceable_filter (:ref:`filter.TraceableFilter `) Only one of :ref:`status_code_filter `, :ref:`duration_filter `, :ref:`not_health_check_filter `, :ref:`traceable_filter `, :ref:`runtime_filter `, :ref:`and_filter `, :ref:`or_filter ` may be set. .. _envoy_api_field_filter.AccessLogFilter.runtime_filter: runtime_filter (:ref:`filter.RuntimeFilter `) Only one of :ref:`status_code_filter `, :ref:`duration_filter `, :ref:`not_health_check_filter `, :ref:`traceable_filter `, :ref:`runtime_filter `, :ref:`and_filter `, :ref:`or_filter ` may be set. .. _envoy_api_field_filter.AccessLogFilter.and_filter: and_filter (:ref:`filter.AndFilter `) Only one of :ref:`status_code_filter `, :ref:`duration_filter `, :ref:`not_health_check_filter `, :ref:`traceable_filter `, :ref:`runtime_filter `, :ref:`and_filter `, :ref:`or_filter ` may be set. .. _envoy_api_field_filter.AccessLogFilter.or_filter: or_filter (:ref:`filter.OrFilter `) Only one of :ref:`status_code_filter `, :ref:`duration_filter `, :ref:`not_health_check_filter `, :ref:`traceable_filter `, :ref:`runtime_filter `, :ref:`and_filter `, :ref:`or_filter ` may be set. .. _envoy_api_msg_filter.FileAccessLog: filter.FileAccessLog -------------------- `[filter.FileAccessLog proto] `_ Custom configuration for an AccessLog that writes log entries directly to a file. Configures the built-in "envoy.file_access_log" AccessLog. .. code-block:: json { "path": "...", "format": "..." } .. _envoy_api_field_filter.FileAccessLog.path: path (`string `_) A path to a local file to which to write the access log entries. .. _envoy_api_field_filter.FileAccessLog.format: format (`string `_) [V2-API-DIFF] In addition to the existing format specifiers, the following additional specifiers will be available: %TLS_SNI_HOSTNAME%: SNI from handshake. %TLS_VERSION%: Possible values include: “TLSv1”, “TLSv1.1”, “TLSv1.2”, “TLSv1.3”. %TLS_CIPHER_SUITE%: Cipher suite negotiated during the TLS handshake. The value is four hex digits defined by the IANA TLS Cipher Suite Registry, e.g. “009C” for TLS_RSA_WITH_AES_128_GCM_SHA256. TODO(htuch): Document how envoy.http_connection_manager.access_log values can be accessed in the format specifier. .. _envoy_api_msg_filter.AccessLogServiceConfig: filter.AccessLogServiceConfig ----------------------------- `[filter.AccessLogServiceConfig proto] `_ Configuration for the built-in "envoy.grpc_access_log" access log type. .. code-block:: json { "log_name": "...", "cluster_name": "..." } .. _envoy_api_field_filter.AccessLogServiceConfig.log_name: log_name (`string `_) The friendly name of the access log to be returned in StreamAccessLogsMessage.Identifier. This allows the access log server to differentiate between different access logs coming from the same Envoy. .. _envoy_api_field_filter.AccessLogServiceConfig.cluster_name: cluster_name (`string `_) The name of the upstream cluster that hosts the access log service. The cluster must be configured in the cluster manager. .. _envoy_api_msg_filter.StreamAccessLogsMessage: filter.StreamAccessLogsMessage ------------------------------ `[filter.StreamAccessLogsMessage proto] `_ Stream message for the StreamAccessLogs API. Envoy will open a stream to the server and stream access logs without ever expecting a response. .. code-block:: json { "identifier": "{...}", "logs": [] } .. _envoy_api_field_filter.StreamAccessLogsMessage.identifier: identifier (:ref:`filter.StreamAccessLogsMessage.Identifier `) Identifier data that will only be sent in the first message on the stream. This is effectively structured metadata and is a performance optimization. .. _envoy_api_field_filter.StreamAccessLogsMessage.logs: logs (:ref:`filter.AccessLogEntry `) A list of access logs. .. _envoy_api_msg_filter.StreamAccessLogsMessage.Identifier: filter.StreamAccessLogsMessage.Identifier ----------------------------------------- `[filter.StreamAccessLogsMessage.Identifier proto] `_ .. code-block:: json { "node": "{...}", "log_name": "..." } .. _envoy_api_field_filter.StreamAccessLogsMessage.Identifier.node: node (:ref:`Node `) The node sending the access log messages over the stream. .. _envoy_api_field_filter.StreamAccessLogsMessage.Identifier.log_name: log_name (`string `_) The friendly name of the log configured in AccessLogServiceConfig. .. _envoy_api_msg_filter.StreamAccessLogsResponse: filter.StreamAccessLogsResponse ------------------------------- `[filter.StreamAccessLogsResponse proto] `_ Empty response for the StreamAccessLogs API. Will never be sent. See below. .. code-block:: json { } .. _envoy_api_msg_filter.AccessLog: filter.AccessLog ---------------- `[filter.AccessLog proto] `_ .. code-block:: json { "name": "...", "filter": "{...}", "config": "{...}" } .. _envoy_api_field_filter.AccessLog.name: name (`string `_) The name of the access log implementation to instantiate. The name must match a statically registered access log. Current built-in loggers include: 1) "envoy.file_access_log" 2) "envoy.grpc_access_log" .. _envoy_api_field_filter.AccessLog.filter: filter (:ref:`filter.AccessLogFilter `) Filter which is used to determine if the access log needs to be written. .. _envoy_api_field_filter.AccessLog.config: config (`Struct `_) Custom configuration that depends on the access log being instantiated. built-in configurations include: 1) "envoy.file_access_log": FileAccessLog 2) "envoy.grpc_access_log": AccessLogServiceConfig